============================================================================================
                                                                      a pointer table &
----------------                                                              script utility
                ----- c _____
             		     -----r_____
                        		-----u_____
                                   		   -----m_____                
                                              		      -----b_____
                                                                         ________v1.0________
               ==============================
                               an abstract crouton production
                               ______________________________******************^ **********
           2003                                                                          
    occluded hairdo
               =============================================================================


  i. update history

                                ii. what the hell is this?

        iii. main panel                                                 ***

                iv. file panel

                        v. calculations panel

                                vi. program limits                                *
                                                                                   ---------
                                        vii. miscellaneous info
                
^ ------------==============================================================


	<><><><><><><><><
	i. update history
	><><><><><><><><>

v1.0 1/11/10 - initial release.


                               =============================================================


<><><><><><><><><><><><><>
ii. what the hell is this?
<><><><><><><><><><><><><>


	this is a program designed to easily calculate all types of pointer tables. a
	pointer table is a block of data that accompanies the script in nes, snes, and other
 	types of video games. if this sounds like something other than english to you, read
	some of the excellent pointer table docs available on the net (anus p's, mad
	hacker's). crumb can also be used as a stand-alone script inserter.

	to use crumb, you basically need a script file (dumped using a hex editor like
	thingy or translhextion), a rom, and a little bit of information on where stuff is
	stored in the game. the program inserts the script and then figures out the
	pointers. if you like, you can insert your script in another program and then use
        crumb only to do the pointers.

	there are similar programs out there, but as far as i know, none is as customizable
	as this. the options may seem overwhelming at first, especially if you're a newbie,
	but this text file should help you out. good luck.

	this program was coded in java - as you'll notice by the annoying coffee-cup icon -
	and you must have the java virtual machine installed to run it.


                               =============================================================


	<><><><><><><><
	iii. main panel
	><><><><><><><>


[insert script] the program can calculate pointers based on a script that has already been
inserted into the rom. if you don't want to insert a new script, turn this option off.

[calculate pointers] alternately, you can use the program as a script inserter and not
calculate pointers at all. if that's what you want to do, turn this option off.

[save config] saves this configuration for later use. you can easily find the config file
and edit it with notepad, dos edit, or whatever the hell else you want if you don't feel
like opening up the program to change options.

[load config] i dunno. i'm confused.

[backup rom] for your convenience, creates a backup of the rom you're currently working
with. it will be added to the same directory as the original with the file extension ".bak"
appended.

[do it!] is this something naughty?


==============================================================


<><><><><><><>
iv. file panel
<><><><><><><>


	[rom] enter the rom filename here.

	[script] enter the script filename here.

	[table] enter the table filename here.

	[script info: address] here you will enter the starting address of the script as a
	hex number. if the code that separates text blocks is also found before the start of
	the text, use the address of the text block code (and include this code in your
	script), as this is most likely what the first pointer will point to.

	[script info: length] only needed if you are not inserting a script. this value must
	be entered as a hex number.

	[text block start/end code] the hex that the game uses to designate either the start
	or end of a text block, line, whatever (this is often "00" or "ff").

	[raw hex start/end codes] if the program finds these characters in the script, it
 	will stop writing table values and start writing raw hex. for example, say your
 	script contains "*01020304*," where "*" is the raw hex end and start code (yep, they
 	can be the same thing). the asterisks will be disregarded and the bytes "01 02 03
	04" will be written to the rom. be warned that this program don't take kindly to
	spaces or non-hex values imbedded in hex blocks. also, the codes can be only one
	character long, though they can be any bizarre characters you want.


                               =============================================================


	<><><><><><><><><><><
	v. calculations panel
	><><><><><><><><><><>


[pointer table start address] enter the starting address of the pointer table in hex here.

[pointer length] the length in bytes of each pointer. if the length you choose is greater
than any of the text block code addresses contained in the script, those addresses will be
padded with 00s when the pointer is calculated (e.g. if you enter 3 for the length, the
address 270f will become 00270f). if it is less than any of the block code addresses, those
addresses will be cut off at the front (e.g. 0244ab will become 44ab). enter a decimal
number here.

[spaces between pointer bytes] normally, you'll want to have this set to 0, but if you're
dealing with some kind of weird pointer storage system where the bytes in the pointers are
broken up, you can enter whatever value you need to here. here's an example of a situation
in which you would want to enter some other value: let's say you have a pointer table that
contains just two pointers (not likely, but...). these pointers, when decoded, are "55 0f"
and "87 70," but the game stores them as "55 87 0f 70." in this case, you would enter 1 in
the box.

[hex to insert between pointers] some roms might store some kind of hex between pointers.
if your rom does this, enter that hex here. note that whatever you enter here will not be
written before the first pointer or after the last, so you'll have to do that by hand if
necessary.

[reverse address] you will want to enable this option in most circumstances. it tells the
program to reverse the bytes in the address when calculating pointers (e.g. 44ab will become
ab44).

[address add/subtract value] type and amount are used jointly to indicate what value, if
any, to add or subtract from the addresses of the block codes to reach the pointer values.
if you need to subtract 10 from the address when calculating the pointer (common for nes
games), you would select "-" and enter 10 as the amount. by the way, the amount must be
entered in hex.

[point to] tells the program whether the pointer refers to the hex codes that separate text
areas or the actual proceeding text. obviously, pointing to the block code is only an option
if the storage system is set up so that the code indicates the beginning rather than the end
of the text. generally, this option should be set to refer to the text.


==============================================================


<><><><><><><><><>
vi. program limits
<><><><><><><><><>


	your table file cannot contain a hex entry greater than 7F FF FF FF FF FF FF FF.

	if the same text is entered under more than one hex value, the program will find one
	of the hex values to write, but it may not find the one you want.

	if your script contains a character that isn't in the table, that character will be
	skipped. you will be notified when script insertion is over that the script
	contained an unwriteable character.

	multiple tile and multiple byte encoding are fully supported.

	efforts to write areas of the rom after address 7F FF FF FF will fail. this won't be
	a problem unless your rom is larger than 2.15 gigs (!), though.

	if your table file contains bookmarks or lines like "/00," you can take em out or
	leave em in as you please. the program will just ignore them. at this time, the
	program *does not* try to match up funny text like "{end}" or whatever with 
	special values like this in the table. some hex editors use these codes when dumping
	text, so beware. you can probably think of ways around this: making a table entry
	with matching hex for "{end}," etc.

	note that if you select point to text and the very last byte of the script is part
	of a text block code, that code will be disregarded because there is no way for the
	program to tell if there is text after it in the rom or not. you will need to pay
	attention to this if you are inserting only part of a script, but otherwise, don't
	worry about it.

	be aware that some games do not store pointers in a strictly sequential manner -
	for instance, castlevania 2, which, unadvisably, I used to test this program. (the
	game repeats certain pointers - god knows why, and i don't really care because i
	don't have any desire to hack it.) if you're getting funny results, this could be
	the cause.


                               =============================================================


	<><><><><><><><><><><><
	vii. miscellaneous info
	><><><><><><><><><><><>

crumb was coded in java. it is available, with source, from the abstract crouton website:
http://abstractcrouton.emuxhaven.net. you can use it for whatever you want, but i'm not
responsible if it screws up any of your projects in any way (it shouldn't). you're free to
incorporate my code into software of your own, so long as it is made available on a not-
for-profit basis and i am given credit.

if you find a type of pointer table that this program can't handle, please let me know about
it. also, i'm open to feature suggestions and welcome bug reports.

thanks to real's how-to (http://www.rgagnon.com/howto.html), from which i stole the code
that sets the max input to some of the text fields.

oh yeah, and don't worry; the formatting of this text file is screwed up because i want it
to be. it's "abstract," get it?

i had originally planned to include an auto-calc feature that would calculate certain types
of pointer tables without tons of options being specified by the user, but have decided not
to do so for the time being. for one, this would be time-consuming and hold up the release
of the program. also, it's probably pretty likely that most rom hackers either already know
or can easily learn how pointer tables work... and it's a good exercise to do it yourself
anyway. this program can still save you a huge amount of work that you would otherwise have
to do by hand. if anyone really wants to see the auto-calc feature implemented, email me,
and if interest is high, i might do it (if i get bored, i might do it anyway).


==============================================================


	everything relevant by occluded hairdo
		abstract crouton productions 2003
			http://abstractcrouton.emuxhaven.net/